/*-------------------------------------------------------------------------
 *
 * int128.h
 *	  自定义的 128 位整数算术。
 *
 * 如果有原生的 int128 类型，我们就使用它；否则基于两个 int64 的一半来实现。
 *
 * 请参阅 src/tools/testint128.c 以获取对此文件的简单测试工具。
 *
 * Copyright (c) 2017-2022, PostgreSQL Global Development Group
 *
 * src/include/common/int128.h
 *
 *-------------------------------------------------------------------------
 */
#ifndef INT128_H
#define INT128_H

/*
 * 出于测试目的，可以通过预定义 USE_NATIVE_INT128 来开启/关闭原生 int128 的使用。
 */
#ifndef USE_NATIVE_INT128
#ifdef HAVE_INT128
#define USE_NATIVE_INT128 1
#else
#define USE_NATIVE_INT128 0
#endif
#endif


#if USE_NATIVE_INT128

typedef int128 INT128;

/*
 * 将一个无符号 int64 值加到一个 INT128 变量中。
 */
static inline void
int128_add_uint64(INT128 *i128, uint64 v)
{
	*i128 += v;
}

/*
 * 将一个有符号 int64 值加到一个 INT128 变量中。
 */
static inline void
int128_add_int64(INT128 *i128, int64 v)
{
	*i128 += v;
}

/*
 * 将两个 int64 值的 128 位乘积加到一个 INT128 变量中。
 *
 * XXX 如果编译器性能不佳，这实际上可能比其他实现效率更低；也许我们应该始终手动处理它？
 */
static inline void
int128_add_int64_mul_int64(INT128 *i128, int64 x, int64 y)
{
	*i128 += (int128) x * (int128) y;
}

/*
 * 比较两个 INT128 值，返回 -1、0 或 +1。
 */
static inline int
int128_compare(INT128 x, INT128 y)
{
	if (x < y)
		return -1;
	if (x > y)
		return 1;
	return 0;
}

/*
 * 将 int64 扩展到 INT128。
 */
static inline INT128
int64_to_int128(int64 v)
{
	return (INT128) v;
}

/*
 * 将 INT128 转换为 int64（丢失任何高位）。
 * 这对于降级到 uint64 也同样有效。
 */
static inline int64
int128_to_int64(INT128 val)
{
	return (int64) val;
}

#else							/* !USE_NATIVE_INT128 */

/*
 * 我们将 INT128 结构布局为与原生 int128 类型（可能）相同的内容和字节顺序。这对 INT128 的普通使用没有影响，但允许将 INT128 与 int128 进行联合以用于测试目的。
 */
typedef struct
{
#ifdef WORDS_BIGENDIAN
	int64		hi;				/* 最重要的 64 位，包括符号 */
	uint64		lo;				/* 最不重要的 64 位，未包含符号 */
#else
	uint64		lo;				/* 最不重要的 64 位，未包含符号 */
	int64		hi;				/* 最重要的 64 位，包括符号 */
#endif
} INT128;

/*
 * 将一个无符号 int64 值加到一个 INT128 变量中。
 */
static inline void
int128_add_uint64(INT128 *i128, uint64 v)
{
	/*
	 * 首先将值加到 .lo 部分，然后检查是否需要将进位传播到 .hi 部分。如果两个输入都有高位设置，或者仅一个输入有高位设置而新的 .lo 部分没有，则需要进位。记住 .lo 部分是无符号的；我们在这里转换为有符号的，只是便宜地检查高位。
	 */
	uint64		oldlo = i128->lo;

	i128->lo += v;
	if (((int64) v < 0 && (int64) oldlo < 0) ||
		(((int64) v < 0 || (int64) oldlo < 0) && (int64) i128->lo >= 0))
		i128->hi++;
}

/*
 * 将一个有符号 int64 值加到一个 INT128 变量中。
 */
static inline void
int128_add_int64(INT128 *i128, int64 v)
{
	/*
	 * 这与上述情况非常相似，只是对负数的进位逻辑有所不同。通常，我们需要从 .hi 部分减去 1（对应于将 v 的符号扩展位加到其中）；但如果 .lo 部分有进位输出，那么就取消这个操作，我们不做任何事情。
	 */
	uint64		oldlo = i128->lo;

	i128->lo += v;
	if (v >= 0)
	{
		if ((int64) oldlo < 0 && (int64) i128->lo >= 0)
			i128->hi++;
	}
	else
	{
		if (!((int64) oldlo < 0 || (int64) i128->lo >= 0))
			i128->hi--;
	}
}

/*
 * INT64_AU32 提取 int64 的最重要 32 位作为 int64，而 INT64_AL32 提取最不重要 32 位作为 uint64。
 */
#define INT64_AU32(i64) ((i64) >> 32)
#define INT64_AL32(i64) ((i64) & UINT64CONST(0xFFFFFFFF))

/*
 * 将两个 int64 值的 128 位乘积加到一个 INT128 变量中。
 */
static inline void
int128_add_int64_mul_int64(INT128 *i128, int64 x, int64 y)
{
	/* INT64_AU32 必须使用算术右移 */
	StaticAssertStmt(((int64) -1 >> 1) == (int64) -1,
					 "arithmetic right shift is needed");

	/*----------
	 * 使用 64 位算术形成 128 位乘积 x * y。
	 * 将每个 64 位输入视为 32 位高位和低位部分，
	 * 我们可以计算
	 *
	 *	 x * y = ((x.hi << 32) + x.lo) * (((y.hi << 32) + y.lo)
	 *		   = (x.hi * y.hi) << 64 +
	 *			 (x.hi * y.lo) << 32 +
	 *			 (x.lo * y.hi) << 32 +
	 *			 x.lo * y.lo
	 *
	 * 每个单独的乘积是 32 位项，因此在 64 位算术中计算时不会溢出。
	 * 然后我们只需在将其添加到 128 位结果时将其移到正确的位置。
	 * 我们还必须记住，“lo”部分必须作为无符号数处理。
	 *----------
	 */

	/* 如果乘积必须为零，则无需努力工作 */
	if (x != 0 && y != 0)
	{
		int64		x_u32 = INT64_AU32(x);
		uint64		x_l32 = INT64_AL32(x);
		int64		y_u32 = INT64_AU32(y);
		uint64		y_l32 = INT64_AL32(y);
		int64		tmp;

		/* 第一个项 */
		i128->hi += x_u32 * y_u32;

		/* 第二个项：仅在 x 为负时进行符号扩展 */
		tmp = x_u32 * y_l32;
		if (x < 0)
			i128->hi += INT64_AU32(tmp);
		else
			i128->hi += ((uint64) tmp) >> 32;
		int128_add_uint64(i128, ((uint64) INT64_AL32(tmp)) << 32);

		/* 第三个项：仅在 y 为负时进行符号扩展 */
		tmp = x_l32 * y_u32;
		if (y < 0)
			i128->hi += INT64_AU32(tmp);
		else
			i128->hi += ((uint64) tmp) >> 32;
		int128_add_uint64(i128, ((uint64) INT64_AL32(tmp)) << 32);

		/* 第四个项：始终为无符号 */
		int128_add_uint64(i128, x_l32 * y_l32);
	}
}

/*
 * 比较两个 INT128 值，返回 -1、0 或 +1。
 */
static inline int
int128_compare(INT128 x, INT128 y)
{
	if (x.hi < y.hi)
		return -1;
	if (x.hi > y.hi)
		return 1;
	if (x.lo < y.lo)
		return -1;
	if (x.lo > y.lo)
		return 1;
	return 0;
}

/*
 * 将 int64 扩展到 INT128。
 */
static inline INT128
int64_to_int128(int64 v)
{
	INT128		val;

	val.lo = (uint64) v;
	val.hi = (v < 0) ? -INT64CONST(1) : INT64CONST(0);
	return val;
}

/*
 * 将 INT128 转换为 int64（丢失任何高位）。
 * 这对于降级到 uint64 也同样有效。
 */
static inline int64
int128_to_int64(INT128 val)
{
	return (int64) val.lo;
}

#endif							/* USE_NATIVE_INT128 */

#endif							/* INT128_H */
